Using the AddManipulator

We'll start with the AddManipulator. Here's a very simple view that takes POSTed data from the browser and creates a new Place object:

from django.core.exceptions import Http404
from django.core.extensions import render_to_response
from django.utils.httpwrappers import HttpResponse, HttpResponseRedirect
from django.models.places import places
from django.core import formfields

def naive_create_place(request):
    """A naive approach to creating places; don't actually use this!"""
    # Create the AddManipulator.
    manipulator = places.AddManipulator()

    # Make a copy of the POSTed data so that do_html2python can
    # modify it in place (request.POST is immutable).
    new_data = request.POST.copy()

    # Convert the request data (which will all be strings) into the
    # appropriate Python types for those fields.
    manipulator.do_html2python(new_data)

    # Save the new object.
    new_place = manipulator.save(new_data)

    # It worked!
    return HttpResponse("Place created: %s" % new_place)

The naive_create_place example works, but as you probably can tell, this view has a number of problems:

• No validation of any sort is performed. If, for example, the name field isn't given in request.POST, the save step will cause a database error because that field is required. Ugly.
• Even if you do perform validation, there's still no way to give that information to the user is any sort of useful way.
• You'll have to separately create a form (and view) that submits to this page, which is a pain and is redundant.

Let's dodge these problems momentarily to take a look at how you could create a view with a form that submits to this flawed creation view:

def naive_create_place_form(request):
    """Simplistic place form view; don't actually use anything like this!"""
    # Create a FormWrapper object that the template can use. Ignore
    # the last two arguments to FormWrapper for now.
    form = formfields.FormWrapper(places.AddManipulator(), {}, {})
    return render_to_response('places/naive_create_form', {'form': form})

(This view, as well as all the following ones, has the same imports as in the first example above.)

The formfields.FormWrapper object is a wrapper that templates can easily deal with to create forms. Here's the naive_create_form template:

{% extends "base" %}

{% block content %}
<h1>Create a place:</h1>

<form method="post" action="../do_new/">
<p><label for="id_name">Name:</label> {{ form.name }}</p>
<p><label for="id_address">Address:</label> {{ form.address }}</p>
<p><label for="id_city">City:</label> {{ form.city }}</p>
<p><label for="id_state">State:</label> {{ form.state }}</p>
<p><label for="id_zip_code">Zip:</label> {{ form.zip_code }}</p>
<p><label for="id_place_type">Place type:</label> {{ form.place_type }}</p>
<input type="submit" />
</form>
{% endblock %}

Before we get back to the problems with these naive set of views, let's go over some salient points of the above template:

* Field "widgets" are handled for you: ``{{ form.field }}`` automatically
  creates the "right" type of widget for the form, as you can see with the
  ``place_type`` field above.

* There isn't a way just to spit out the form. You'll still need to define
  how the form gets laid out. This is a feature: Every form should be
  designed differently. Django doesn't force you into any type of mold.
  If you must use tables, use tables. If you're a semantic purist, you can
  probably find better HTML than in the above template.

* To avoid name conflicts, the ``id``s of form elements take the form
  "id_*fieldname*".

By creating a creation form we've solved problem number 3 above, but we still don't have any validation. Let's revise the validation issue by writing a new creation view that takes validation into account:

def create_place_with_validation(request):
    manipulator = places.AddManipulator()
    new_data = request.POST.copy()

    # Check for validation errors
    errors = manipulator.get_validation_errors(new_data)
    if errors:
        return render_to_response('places/errors', {'errors': errors})
    else:
        manipulator.do_html2python(request.POST)
        new_place = manipulator.save(request.POST)
        return HttpResponse("Place created: %s" % new_place)

In this new version, errors will be found -- manipulator.get_validation_errors handles all the validation for you -- and those errors can be nicely presented on an error page (templated, of course):

{% extends "base" %}

{% block content %}

<h1>Please go back and correct the following error{{ errors|pluralize }}:</h1>
<ul>
    {% for e in errors.items %}
    <li>Field "{{ e.0 }}": {{ e.1|join:", " }}</li>
    {% endfor %}
</ul>

{% endblock %}

Still, this has its own problems:

• There's still the issue of creating a separate (redundant) view for the submission form.
• Errors, though nicely presented, are on a separate page, so the user will have to use the "back" button to fix errors. That's ridiculous and unusable.

The best way to deal with these issues is to collapse the two views -- the form and the submission -- into a single view. This view will be responsible for creating the form, validating POSTed data, and creating the new object (if the data is valid). An added bonus of this approach is that errors and the form will both be available on the same page, so errors with fields can be presented in context.

Below is the finished view:

def create_place(request):
    manipulator = places.AddManipulator()

    if request.POST:
        # If data was POSTed, we're trying to create a new Place.
        new_data = request.POST.copy()

        # Check for errors.
        errors = manipulator.get_validation_errors(new_data)

        if not errors:
            # No errors. This means we can save the data!
            manipulator.do_html2python(new_data)
            new_place = manipulator.save(new_data)

            # Redirect to the object's "edit" page. Always use a redirect
            # after POST data, so that reloads don't accidently create
            # duplicate entires, and so users don't see the confusing
            # "Repost POST data?" alert box in their browsers.
            return HttpResponseRedirect("/places/edit/%i/" % new_place.id)
    else:
        # No POST, so we want a brand new form without any data or errors.
        errors = new_data = {}

    # Create the FormWrapper, template, context, response.
    form = formfields.FormWrapper(manipulator, new_data, errors)
    return render_to_response('places/create_form', {'form': form})

and here's the create_form template:

{% extends "base" %}

{% block content %}
<h1>Create a place:</h1>

{% if form.has_errors %}
<h2>Please correct the following error{{ errors|pluralize }}:</h2>
{% endif %}

<form method="post" action=".">
<p>
    <label for="id_name">Name:</label> {{ form.name }}
    {% if form.name.errors %}*** {{ form.name.errors|join:", " }}{% endif %}
</p>
<p>
    <label for="id_address">Address:</label> {{ form.address }}
    {% if form.address.errors %}*** {{ form.address.errors|join:", " }}{% endif %}
</p>
<p>
    <label for="id_city">City:</label> {{ form.city }}
    {% if form.city.errors %}*** {{ form.city.errors|join:", " }}{% endif %}
</p>
<p>
    <label for="id_state">State:</label> {{ form.state }}
    {% if form.state.errors %}*** {{ form.state.errors|join:", " }}{% endif %}
</p>
<p>
    <label for="id_zip_code">Zip:</label> {{ form.zip_code }}
    {% if form.zip_code.errors %}*** {{ form.zip_code.errors|join:", " }}{% endif %}
</p>
<p>
    <label for="id_place_type">Place type:</label> {{ form.place_type }}
    {% if form.place_type.errors %}*** {{ form.place_type.errors|join:", " }}{% endif %}
</p>
<input type="submit" />
</form>
{% endblock %}

The second two arguments to FormWrapper (new_data and errors) deserve some mention.

The first is any "default" data to be used as values for the fields. Pulling the data from request.POST, as is done above, makes sure that if there are errors, the values the user put in aren't lost. If you try the above example, you'll see this in action.

The second argument is the error list retrieved from manipulator.get_validation_errors. When passed into the FormWrapper, this gives each field an errors item (which is a list of error messages associated with the field) as well as a html_error_list item, which is a <ul> of error messages. The above template uses these error items to display a simple error message next to each field.

Using the ChangeManipulator

The above has covered using the AddManipulator to create a new object. What about editing an existing one? It's shockingly similar to creating a new one:

def edit_place(request, place_id):
    # Get the place in question from the database and create a
    # ChangeManipulator at the same time.
    try:
        manipulator = places.ChangeManipulator(place_id)
    except places.PlaceDoesNotExist:
        raise Http404

    # Grab the Place object in question for future use.
    place = manipulator.original_object

    if request.POST:
        new_data = request.POST.copy()
        errors = manipulator.get_validation_errors(new_data)
        if not errors:
            manipulator.do_html2python(new_data)
            manipulator.save(new_data)

            # Do a post-after-redirect so that reload works, etc.
            return HttpResponseRedirect("/places/edit/%i/" % place.id)
    else:
        errors = {}
        # This makes sure the form accurate represents the fields of the place.
        new_data = place.__dict__

    form = formfields.FormWrapper(manipulator, new_data, errors)
    return render_to_response('places/edit_form', {'form': form, 'place': place})

The only real differences are:

• We create a ChangeManipulator instead of an AddManipulator. The argument to a ChangeManipulator is the ID of the object to be changed. As you can see, the initializer will raise an ObjectDoesNotExist exception if the ID is invalid.
• ChangeManipulator.original_object stores the instance of the object being edited.
• We set new_data to the original object's __dict__. This makes sure the form fields contain the current values of the object. FormWrapper does not modify new_data in any way, and templates cannot, so this is perfectly safe.
• The above example uses a different template, so create and edit can be "skinned" differently if needed, but the form chunk itself is completely identical to the one in the create form above.

The astute programmer will notice the add and create functions are nearly identical and could in fact be collapsed into a single view. This is left as an exercise for said programmer.

(However, the even-more-astute programmer will take heed of the note at the top of this document and check out the generic views documentation if all she wishes to do is this type of simple create/update.)